append-transform

What is append-transform?

The append-transform npm package allows you to append transformations to the require.extensions object, enabling you to modify the behavior of require calls for specific file types. This can be useful for tasks such as transpiling code on the fly or adding custom loaders for non-JavaScript files.

What are append-transform's main functionalities?

Append a transformation to require.extensions

This feature allows you to append a transformation function to the require.extensions object. In this example, any .txt file required will be transformed into a module that exports the file's content as a string.

const appendTransform = require('append-transform');

appendTransform(function (code, filename) {
  if (filename.endsWith('.txt')) {
    return `module.exports = ${JSON.stringify(code)}`;
  }
  return code;
});

const content = require('./example.txt');
console.log(content);

Conditional transformation based on file extension

This feature demonstrates how to conditionally apply transformations based on the file extension. In this example, any .js file required will have a comment added at the top of its content.

const appendTransform = require('append-transform');

appendTransform(function (code, filename) {
  if (filename.endsWith('.js')) {
    return `// Transformed\n${code}`;
  }
  return code;
});

const script = require('./example.js');
console.log(script);

Other packages similar to append-transform

pirates

The pirates package provides a way to hook into Node's require system to add custom loaders for different file types. It is similar to append-transform but offers more flexibility and control over the transformation process.

babel-register

babel-register is a package that hooks into Node's require system to automatically transpile JavaScript files using Babel. It is more specialized than append-transform, focusing specifically on Babel transformations.

ts-node

ts-node is a TypeScript execution environment and REPL for Node.js. It allows you to run TypeScript code directly without precompiling, similar to how append-transform can be used to transform code on the fly.

README

append-transform

Install a transform to require.extensions that always runs last, even if additional extensions are added later.

The typical require extension looks something like this:

  var myTransform = require('my-transform');
  
  var oldExtension = require.extensions['.js'];
  require.extensions['.js'] = function (module, filename) {
    var oldCompile = module._compile;
    module._compile = function (code, filename) {
      code = myTransform(code);
      module._compile = oldCompile;
      module._compile(code, filename);
    };  
    oldExtension(module, filename);
  };

In almost all cases, that is sufficient and is the method that should be used (check out pirates for an easy way to do it correctly). In rare cases you must ensure your transform remains the last one, even if other transforms are added later. For example, nyc uses this module to ensure its transform is applied last so it can capture the final source-map information, and ensure any language extensions it can't understand are already transpiled (ES2015 via babel for instance).

WARNING: You should be sure you actually need this, as it takes control away from the user. Your transform remains the last one applied, even as users continue to add more transforms. This is potentially confusing. Coverage libraries like nyc (and istanbul on which it relies) have valid reasons for doing this, but you should prefer conventional transform installation via pirates.

References:

• Detailed Breakdown of How Require Extensions Work
• The test suite provides a good overview of how this library manipulates the order in which transforms are applied.

Install

$ npm install --save append-transform

Usage

var appendTransform = require('append-transform');
var myTransform = require('my-transform');

appendTransform(function (code, filename) {
  if (myTransform.shouldTransform(filename)) {
    code = myTransform.transform(code);
  }
  return code;
});

API

appendTransform(transformFn, [extension])

transformFn

Type: function(code: string, filename: string)
Required

A callback that modifies the incoming code argument in some way, and returns the transformed result. filename is provided to filter which files the transform applies to. If a transform should not manipulate a particular file, just return code without modifying it. It is fairly common to avoid transforming files in node_modules. In that case you may want to use node-modules-regexp to help reliably detect node_modules paths and avoid transforming them.

extension

Type: string
Default: ".js"

The extension for the types of files this transform is capable of handling.

License

MIT © James Talmage